SGI Freeware 1999 August/SGI Freeware 1999 August.iso/dist/fw_perl.idb/usr/freeware/catman/p_man/cat3/IO::Handle.Z/IO::Handle

Text File | 1998-10-28 | 7.8 KB | 265 lines

     IIIIOOOO::::::::HHHHaaaannnnddddlllleeee((((3333))))   22223333////JJJJuuuullll////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))     IIIIOOOO::::::::HHHHaaaannnnddddlllleeee((((3333))))



     NNNNAAAAMMMMEEEE
      IO::Handle - supply object methods for I/O handles

     SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
          use IO::Handle;

          $fh = new    IO::Handle;
          if ($fh->fdopen(fileno(STDIN),"r")) {
          print    $fh->getline;
          $fh->close;
          }

          $fh = new    IO::Handle;
          if ($fh->fdopen(fileno(STDOUT),"w")) {
          $fh->print("Some text\n");
          }

          use IO::Handle '_IOLBF';
          $fh->setvbuf($buffer_var,    _IOLBF,    1024);

          undef $fh;       # automatically closes the file if it's open

          autoflush    STDOUT 1;


     DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
      IO::Handle is    the base class for all other IO    handle
      classes. It is not intended that objects of IO::Handle would
      be created directly, but instead IO::Handle is inherited
      from by several other    classes    in the IO hierarchy.

      If you are reading this documentation, looking for a
      replacement for the FileHandle package, then I suggest you
      read the documentation for IO::File

      A IO::Handle object is a reference to    a symbol (see the
      Symbol package)

     CCCCOOOONNNNSSSSTTTTRRRRUUUUCCCCTTTTOOOORRRR
      new ()
          Creates a    new IO::Handle object.

      new_from_fd (    FD, MODE )
          Creates a    IO::Handle like    new does.  It requires two
          parameters, which    are passed to the method fdopen; if
          the fdopen fails,    the object is destroyed. Otherwise, it
          is returned to the caller.

     MMMMEEEETTTTHHHHOOOODDDDSSSS
      See the _p_e_r_l_f_u_n_c manpage for complete    descriptions of    each
      of the following supported IO::Handle    methods, which are
      just front ends for the corresponding    built-in functions:



     Page 1                        (printed 10/23/98)






     IIIIOOOO::::::::HHHHaaaannnnddddlllleeee((((3333))))   22223333////JJJJuuuullll////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))     IIIIOOOO::::::::HHHHaaaannnnddddlllleeee((((3333))))



          close
          fileno
          getc
          eof
          read
          truncate
          stat
          print
          printf
          sysread
          syswrite

      See the _p_e_r_l_v_a_r manpage for complete descriptions of each of
      the following    supported IO::Handle methods:

          autoflush
          output_field_separator
          output_record_separator
          input_record_separator
          input_line_number
          format_page_number
          format_lines_per_page
          format_lines_left
          format_name
          format_top_name
          format_line_break_characters
          format_formfeed
          format_write

      Furthermore, for doing normal    I/O you    might need these:

      $fh->fdopen (    FD, MODE )
           fdopen is like an ordinary open except that its first
           parameter is not    a filename but rather a    file handle
           name, a IO::Handle object, or a file descriptor number.

      $fh->opened
           Returns true if the object is currently a valid file
           descriptor.

      $fh->getline
           This works like <$fh> described in the section on _I/_O
           _O_p_e_r_a_t_o_r_s in the    _p_e_r_l_o_p manpage except that it's    more
           readable    and can    be safely called in an array context
           but still returns just one line.

      $fh->getlines
           This works like <$fh> when called in an array context
           to read all the remaining lines in a file, except that
           it's more readable.  It will also _c_r_o_a_k() if
           accidentally called in a    scalar context.




     Page 2                        (printed 10/23/98)






     IIIIOOOO::::::::HHHHaaaannnnddddlllleeee((((3333))))   22223333////JJJJuuuullll////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))     IIIIOOOO::::::::HHHHaaaannnnddddlllleeee((((3333))))



      $fh->ungetc (    ORD )
           Pushes a    character with the given ordinal value back
           onto the    given handle's input stream.

      $fh->write ( BUF, LEN    [, OFFSET }\] )
           This write is like write    found in C, that is it is the
           opposite    of read. The wrapper for the perl write
           function    is called format_write.

      $fh->flush
           Flush the given handle's    buffer.

      $fh->error
           Returns a true value if the given handle    has
           experienced any errors since it was opened or since the
           last call to clearerr.

      $fh->clearerr
           Clear the given handle's    error indicator.

      If the C functions _s_e_t_b_u_f() and/or _s_e_t_v_b_u_f() are available,
      then IO::Handle::setbuf and IO::Handle::setvbuf set the
      buffering policy for an IO::Handle.  The calling sequences
      for the Perl functions are the same as their C
      counterparts--including the constants    _IOFBF,    _IOLBF,    and
      _IONBF for _s_e_t_v_b_u_f()--except that the    buffer parameter
      specifies a scalar variable to use as    a buffer.  WARNING: A
      variable used    as a buffer by setbuf or setvbuf must not be
      modified in any way until the    IO::Handle is closed or    setbuf
      or setvbuf is    called again, or memory    corruption may result!
      Note that you    need to    import the constants _IOFBF, _IOLBF,
      and _IONBF explicitly.

      Lastly, there    is a special method for    working    under ----TTTT and
      setuid/gid scripts:

      $fh->untaint
           Marks the object    as taint-clean,    and as such data read
           from it will also be considered taint-clean. Note that
           this is a very trusting action to take, and appropriate
           consideration for the data source and potential
           vulnerability should be kept in mind.

     NNNNOOOOTTTTEEEE
      A IO::Handle object is a GLOB    reference. Some    modules    that
      inherit from IO::Handle may want to keep object related
      variables in the hash    table part of the GLOB.    In an attempt
      to prevent modules trampling on each other I propose the
      that any such    module should prefix its variables with    its
      own name separated by    _'s. For example the IO::Socket    module
      keeps    a timeout variable in 'io_socket_timeout'.




     Page 3                        (printed 10/23/98)






     IIIIOOOO::::::::HHHHaaaannnnddddlllleeee((((3333))))   22223333////JJJJuuuullll////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))     IIIIOOOO::::::::HHHHaaaannnnddddlllleeee((((3333))))



     SSSSEEEEEEEE AAAALLLLSSSSOOOO
      the _p_e_r_l_f_u_n_c manpage,    the section on _I/_O _O_p_e_r_a_t_o_r_s in    the
      _p_e_r_l_o_p manpage, the _I_O::_F_i_l_e manpage

     BBBBUUUUGGGGSSSS
      Due to backwards compatibility, all filehandles resemble
      objects of class IO::Handle, or actually classes derived
      from that class.  They actually aren't.  Which means you
      can't    derive your own    class from IO::Handle and inherit
      those    methods.

     HHHHIIIISSSSTTTTOOOORRRRYYYY
      Derived from FileHandle.pm by    Graham Barr <_b_o_d_g@_t_i_u_k._t_i._c_o_m>










































     Page 4                        (printed 10/23/98)